[EPIC] x402 Payment Rails — production-grade HTTP payment gate

Executive Summary

This PR evolves the initial in-memory x402 prototype into a production-grade payment infrastructure for Open Stellar. It delivers persistent receipt and subscription storage, automated settlement webhooks with multi-layered SSRF protection, multi-chain settlement quotes (Stellar XLM, Base ETH, BNB Chain), on-chain transaction verification, recurring billing with monthly usage caps, a 5-line developer SDK (@open-stellar/x402), and public APIs backing the x402 service catalog marketplace and payment explorer.

Implemented Sub-Issues & Feature Checklist

• x402 Persistent Receipt Store: Replaced in-memory registry with atomic disk persistence (.data/x402-receipts.json) using process-PID swap files.
• x402 Webhook Callbacks: Automated HTTP POST notifications dispatched upon settlement with redirect: 'manual' SSRF isolation.
• x402 Subscriptions & Recurring Billing: Monthly quota caps, automated renewal cycles, 24-hour grace periods, and paused states.
• Multi-Chain Quotes: Unified quote generation supporting Stellar (XLM), Base (ETH), and BNB Chain (BNB) within a single quote payload.
• npm Developer SDK (@open-stellar/x402): Workspace package exporting withX402() higher-order route wrapper for gating Next.js App Router API routes in 5 lines.
• x402 Service Marketplace: GET /api/protocol/x402/services endpoint serving registered API services with pricing, uptime, and reputation metadata.
• Payment Explorer: /explorer UI & GET /api/explorer/receipts endpoint for querying and filtering receipts by agent, service, or chain.

Technical Architecture & Core Subsystems

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Next.js Route / SDK Consumer                       │
│                                (withX402 Wrapper)                           │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             x402 Payment Engine                             │
│  ┌──────────────────────────┐  ┌──────────────────────┐  ┌───────────────┐ │
│  │   Multi-Chain Quotes     │  │   On-Chain Horizon   │  │ Subscriptions │ │
│  │ (Stellar / Base / BNB)   │  │   Payment Verifier   │  │  & Usage Caps │ │
│  └─────────────┬────────────┘  └──────────┬───────────┘  └───────┬───────┘ │
└────────────────│──────────────────────────│──────────────────────│──────────┘
                 │                          │                      │
                 ▼                          ▼                      ▼
┌──────────────────────────┐   ┌────────────────────────┐  ┌──────────────────┐
│   Receipt Store (.json)  │   │  SSRF-Guarded Webhook   │  │ Subscription     │
│   (PID Swap Writes)      │   │  Dispatcher ('manual') │  │ Store (.json)    │
└──────────────────────────┘   └────────────────────────┘  └──────────────────┘

1. Persistent Storage Infrastructure

• Receipt Store (lib/protocols/x402-receipt-store.ts): Durably persists payment receipts to .data/x402-receipts.json. Writes use process PID + timestamp temporary files (${DB_PATH}.${process.pid}.${timestamp}.tmp) swapped atomically to prevent file corruption during server restarts.
• Subscription Store (lib/protocols/x402-subscription-store.ts): Stores active subscriptions, monthly usage counters (callsUsed), statuses (active, grace, paused), and billing event histories in .data/x402-subscriptions.json. Includes serializeWrite async mutex queues and synchronous durable updates (saveX402SubscriptionStoreRecordSync) to prevent call-counter loss on serverless cold starts.

2. On-Chain Stellar Horizon Verification

• Verifier Engine (lib/protocols/x402.ts): verifyStellarPayment() queries Stellar Horizon API endpoints (https://horizon.stellar.org/transactions/:hash/operations) and verifies transaction success before accepting quotes.
• payment & create_account Schema Mapping: Correctly maps both standard XLM native transfers (to, from, amount, asset_type === 'native') and new account activations (account, funder, starting_balance). Enforces mandatory recipient, sender, and minimum XLM amount matching (op.amount >= expectedAmountXlm), rejecting underpayments or dust attacks.

3. Webhook Delivery & Multi-Layered SSRF Guard

• Dispatcher (lib/protocols/x402-webhooks.ts): dispatchX402SettlementWebhook() posts JSON payloads ({ event: 'x402.settlement', timestamp, receipt }) upon settlement.
• Numeric IP & Domain SSRF Protection: isPrivateOrLoopbackHost() parses hostnames, decimal IPv4 integers (e.g. 2130706433), and IPv4-mapped IPv6 (::ffff:169.254.169.254), rejecting loopback (127.0.0.0/8), private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local/cloud metadata (169.254.0.0/16), .internal, and .local targets.
• HTTP Redirect Isolation: sendWebhookHttpRequest() sets redirect: 'manual' on fetch() calls and rejects 30x HTTP redirects, preventing attackers from bypassing initial domain checks via HTTP redirects.

4. Authentication & Fail-Closed Security

• Route Authorization (app/api/protocol/x402/webhooks/route.ts): isAuthorized() fails closed in production whenever no admin secret is configured.
• Constant-Time Secret Comparison: Utilizes crypto.timingSafeEqual with length-matched byte buffers (safeCompare()) to eliminate timing side-channel attacks on Authorization: Bearer and X-Admin-Secret headers.

5. Developer SDK (@open-stellar/x402)

• Workspace package packages/x402 and wrapper lib/sdk/x402-sdk.ts enable route gating in 5 lines:

  import { withX402 } from '@open-stellar/x402'
  
  export const GET = withX402({ serviceId: 'oracle-service', unitPriceUsd: 0.05 }, async (req) => {
    return Response.json({ data: 'Protected Payload' })
  })

File Changes Matrix

Security Audit & Hardening Matrix

Verification & CI Testing

1. Vitest Unit & Integration Suite:

   npm test
   # Test Files: 103 passed (103)
   # Tests:      640 passed (640)

2. TypeScript Strict Type Check:

   npx tsc --noEmit
   # Exit code 0 (0 errors)

3. CI Dependency Locking:
   Updated package-lock.json with workspace package registry entry @open-stellar/x402 to ensure npm ci succeeds in GitHub Actions Playwright E2E workflows.

Closes #18